core/iter/sources/
repeat_with.rs

1use crate::fmt;
2use crate::iter::{FusedIterator, TrustedLen};
3use crate::ops::Try;
4
5/// Creates a new iterator that repeats elements of type `A` endlessly by
6/// applying the provided closure, the repeater, `F: FnMut() -> A`.
7///
8/// The `repeat_with()` function calls the repeater over and over again.
9///
10/// Infinite iterators like `repeat_with()` are often used with adapters like
11/// [`Iterator::take()`], in order to make them finite.
12///
13/// If the element type of the iterator you need implements [`Clone`], and
14/// it is OK to keep the source element in memory, you should instead use
15/// the [`repeat()`] function.
16///
17/// An iterator produced by `repeat_with()` is not a [`DoubleEndedIterator`].
18/// If you need `repeat_with()` to return a [`DoubleEndedIterator`],
19/// please open a GitHub issue explaining your use case.
20///
21/// [`repeat()`]: crate::iter::repeat
22///
23/// # Examples
24///
25/// Basic usage:
26///
27/// ```
28/// use std::iter;
29///
30/// // let's assume we have some value of a type that is not `Clone`
31/// // or which we don't want to have in memory just yet because it is expensive:
32/// #[derive(PartialEq, Debug)]
33/// struct Expensive;
34///
35/// // a particular value forever:
36/// let mut things = iter::repeat_with(|| Expensive);
37///
38/// assert_eq!(Some(Expensive), things.next());
39/// assert_eq!(Some(Expensive), things.next());
40/// assert_eq!(Some(Expensive), things.next());
41/// assert_eq!(Some(Expensive), things.next());
42/// assert_eq!(Some(Expensive), things.next());
43/// ```
44///
45/// Using mutation and going finite:
46///
47/// ```rust
48/// use std::iter;
49///
50/// // From the zeroth to the third power of two:
51/// let mut curr = 1;
52/// let mut pow2 = iter::repeat_with(|| { let tmp = curr; curr *= 2; tmp })
53///                     .take(4);
54///
55/// assert_eq!(Some(1), pow2.next());
56/// assert_eq!(Some(2), pow2.next());
57/// assert_eq!(Some(4), pow2.next());
58/// assert_eq!(Some(8), pow2.next());
59///
60/// // ... and now we're done
61/// assert_eq!(None, pow2.next());
62/// ```
63#[inline]
64#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
65#[rustc_diagnostic_item = "iter_repeat_with"]
66pub fn repeat_with<A, F: FnMut() -> A>(repeater: F) -> RepeatWith<F> {
67    RepeatWith { repeater }
68}
69
70/// An iterator that repeats elements of type `A` endlessly by
71/// applying the provided closure `F: FnMut() -> A`.
72///
73/// This `struct` is created by the [`repeat_with()`] function.
74/// See its documentation for more.
75#[derive(Copy, Clone)]
76#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
77pub struct RepeatWith<F> {
78    repeater: F,
79}
80
81#[stable(feature = "iterator_repeat_with_debug", since = "1.68.0")]
82impl<F> fmt::Debug for RepeatWith<F> {
83    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
84        f.debug_struct("RepeatWith").finish_non_exhaustive()
85    }
86}
87
88#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
89impl<A, F: FnMut() -> A> Iterator for RepeatWith<F> {
90    type Item = A;
91
92    #[inline]
93    fn next(&mut self) -> Option<A> {
94        Some((self.repeater)())
95    }
96
97    #[inline]
98    fn size_hint(&self) -> (usize, Option<usize>) {
99        (usize::MAX, None)
100    }
101
102    #[inline]
103    fn try_fold<Acc, Fold, R>(&mut self, mut init: Acc, mut fold: Fold) -> R
104    where
105        Fold: FnMut(Acc, Self::Item) -> R,
106        R: Try<Output = Acc>,
107    {
108        // This override isn't strictly needed, but avoids the need to optimize
109        // away the `next`-always-returns-`Some` and emphasizes that the `?`
110        // is the only way to exit the loop.
111
112        loop {
113            let item = (self.repeater)();
114            init = fold(init, item)?;
115        }
116    }
117}
118
119#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
120impl<A, F: FnMut() -> A> FusedIterator for RepeatWith<F> {}
121
122#[unstable(feature = "trusted_len", issue = "37572")]
123unsafe impl<A, F: FnMut() -> A> TrustedLen for RepeatWith<F> {}
core/iter/sources/repeat_with.rs

core/iter/sources/
repeat_with.rs
